docs: generalize doc standard to all crates and config sections by bglusman · Pull Request #83 · bglusman/calciforge

bglusman · 2026-04-29T19:37:09Z

Summary

Broadens the documentation standard from "channels only" to a project-wide gold standard that applies to all user-facing config, public library APIs, and user-facing features across every crate.

The two mechanisms

Library crates (secrets-client, adversary-detector, clashd, mcp-server, paste-server, security-proxy): native Rust doctests in /// comments — cargo test --doc -p <crate> compiles and runs them.

Binary crates (calciforge, host-agent): include_str! + unit tests that load markdown files, extract fenced TOML blocks, and parse them against the live config schema. The channel tests in config.rs are the canonical reference implementation.

What's defined

Which config sections need docs and where they live (docs/agents.md, docs/routing.md, docs/model-gateway.md, etc.)
Five-section structure every setup guide must follow (architecture, prerequisites, config, identity/routing, verify)
Explicit rules for adding fields, config sections, and public functions
Hard rule: no new channel, config section, or public API without tested docs

What this doesn't do

Doesn't add the missing docs yet — that's the next body of work. This PR establishes the standard so any agent or contributor knows exactly what's required when they touch any part of the codebase.

Merge order

Can merge independently of PR #82 (channel setup guides) or after — the standard references the channel tests as the canonical example.

Generated with Claude Code

Adds per-channel setup docs (Telegram, Matrix, Signal, WhatsApp) to docs/channels/ as part of the public docs site (calciforge.org/channels/). Each guide covers: architecture diagram, prerequisites, config TOML, identity/routing wiring, and a verify step. The TOML config blocks in each doc are compile-tested: config.rs grows extract_toml_blocks() + test_channel_docs_<channel>_toml_blocks_valid tests that load each markdown via include_str!, extract every fenced [[channels]] block, and parse it against the live CalciforgeConfig schema. If a field is renamed and the doc isn't updated, cargo test fails. Also adds test_channel_config_<channel>_inline unit tests as schema-correct reference examples for each channel kind. AGENTS.md documents the standard and process: every channel needs a docs/channels/ entry, tests in config.rs, and both must be updated together when the schema changes. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Broadens the documentation standard from channels-only to a project-wide gold standard covering all user-facing config, public library APIs, and user-facing features across all crates. Key points: - Library crates (secrets-client, adversary-detector, etc.) use native Rust doctests (cargo test --doc -p <crate>) - Binary crates (calciforge, host-agent) use the include_str! + unit test pattern established for channels - Every pub struct field needs a doc comment; every TOML example in docs/ must be compile-tested - Defines the five-section structure all setup guides must follow - Table of which doc file maps to which test for each config area - Explicit rule: no new config section, channel, or public API without tested docs; PRs without docs should not be merged Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

qodo-code-review · 2026-04-29T19:37:13Z

ⓘ You've reached your Qodo monthly free-tier limit. Reviews pause until next month — upgrade your plan to continue now, or link your paid account if you already have one.

greptile-apps · 2026-04-29T19:40:37Z

Greptile Summary

This PR establishes a project-wide documentation standard, adds four channel setup guides (telegram.md, matrix.md, signal.md, whatsapp.md), and introduces a config.rs test harness that uses include_str! to parse every fenced TOML block in those docs against the live config schema. The docs/index.md is updated with navigation links to the new guides.

Confidence Score: 5/5

Safe to merge; only one P2 documentation nit about a non-existent function name in an example snippet.

All findings are P2. The test infrastructure is correct and well-structured, the four channel docs are complete and match their inline test fixtures, and the standard itself is clearly written. The single issue (AGENTS.md example referencing doc_blocks_with/parse_as_config which don't exist) is a documentation clarity nit that won't break builds or mislead runtime behaviour.

AGENTS.md — example snippet uses non-existent helper function names

Important Files Changed

Filename	Overview
AGENTS.md	Adds comprehensive documentation standard section; example snippet uses doc_blocks_with/parse_as_config which don't exist in the codebase
crates/calciforge/src/config.rs	Adds test helpers (extract_toml_blocks, channel_blocks_from_doc, parse_channel_block) and 8 tests covering inline TOML and doc-file TOML blocks for all four channels; implementation is clean and correct
docs/channels/telegram.md	New Telegram setup guide with all five required sections; channel TOML block matches the inline test in config.rs
docs/channels/matrix.md	New Matrix setup guide; includes E2EE-not-supported warning, all required sections, and TOML example verified by tests
docs/channels/signal.md	New Signal setup guide; ZeroClaw config block correctly uses [channels_config.signal] so it isn't accidentally caught by the channel-block filter in tests
docs/channels/whatsapp.md	New WhatsApp setup guide; detailed webhook payload, reply API, and HMAC verification sections; TOML examples verified by tests
docs/index.md	Adds navigation links to the four new channel setup guides under the channels section

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["docs/channels/*.md\n(Markdown with fenced TOML blocks)"] --> B["include_str! at compile time\n(config.rs test module)"]
    B --> C["extract_toml_blocks(markdown)\nreturns all fenced toml blocks"]
    C --> D["channel_blocks_from_doc(markdown)\nfilters for blocks containing [[channels]]"]
    D --> E["parse_channel_block(block)\nwraps in [calciforge] envelope\nand calls toml::from_str"]
    E --> F{Parse OK?}
    F -->|yes| G["assert cfg.channels[0].kind == expected"]
    F -->|no| H["panic with block content + error\n(test fails, CI blocks merge)"]
    G --> I["test passes"]

_{Reviews (2): Last reviewed commit: "fix(docs): fix SecretsClient example in ..." | Re-trigger Greptile}

Copilot

Pull request overview

Expands Calciforge’s documentation approach by adding compile-tested channel setup guides and codifying a project-wide “tested docs” standard for user-facing config and public APIs.

Changes:

Adds new channel setup guides under docs/channels/ (Telegram, Matrix, Signal, WhatsApp) with TOML examples intended to stay schema-correct.
Updates crates/calciforge/src/config.rs tests to include_str! the channel docs and parse fenced [[channels]] TOML blocks against the live CalciforgeConfig schema.
Updates AGENTS.md to define the repo-wide documentation/testing standard and links channel guides from docs/index.md.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
docs/index.md	Links to the new per-channel setup guides from the main docs index.
docs/channels/whatsapp.md	Adds a WhatsApp webhook + ZeroClaw/OpenClaw setup guide with config examples.
docs/channels/telegram.md	Adds a Telegram long-poll setup guide with config examples.
docs/channels/signal.md	Adds a Signal webhook + ZeroClaw/OpenClaw setup guide with config examples.
docs/channels/matrix.md	Adds a Matrix `/sync` long-poll setup guide (explicitly notes no E2EE) with config examples.
crates/calciforge/src/config.rs	Adds tests that parse channel-doc TOML blocks to prevent schema drift.
AGENTS.md	Documents the “tested docs” gold standard and how to implement it for crates/config sections.

+| `homeserver` | yes | Full URL of the Matrix homeserver |
+| `access_token_file` | yes | Path to file containing the bot's access token |
+| `room_id` | yes | Internal room ID (starts with `!`) |
+| `allowed_users` | yes | Matrix user IDs permitted to send commands; empty list allows all room members (not recommended) |


+bot will route to the default agent. On an unknown user ID, you'll see
+`no identity for telegram/<id>` — use that output to find the ID if needed.


+/// # use secrets_client::SecretsClient;
+/// let client = SecretsClient::new();
+/// let value = client.resolve("MY_API_KEY")?;


The doctest example used secrets_client::SecretsClient which doesn't exist. The real public API is FnoxClient with an async get() method. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

bglusman · 2026-04-30T11:48:56Z

Closing as superseded by the current docs-test direction and #89. The integration branch includes the relevant docs expansion on top of latest main without the stale conflicts.

Librarian and others added 3 commits April 29, 2026 19:09

style: cargo fmt on channel config tests

86553af

Copilot AI review requested due to automatic review settings April 29, 2026 19:37

Copilot started reviewing on behalf of bglusman April 29, 2026 19:37 View session

Copilot AI reviewed Apr 29, 2026

View reviewed changes

fix(docs): fix SecretsClient example in AGENTS.md

0f162da

The doctest example used secrets_client::SecretsClient which doesn't exist. The real public API is FnoxClient with an async get() method. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

bglusman closed this Apr 30, 2026

bglusman deleted the docs/extend-doc-standard branch May 1, 2026 17:20

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: generalize doc standard to all crates and config sections#83

docs: generalize doc standard to all crates and config sections#83
bglusman wants to merge 4 commits into
mainfrom
docs/extend-doc-standard

bglusman commented Apr 29, 2026

Uh oh!

qodo-code-review Bot commented Apr 29, 2026

Uh oh!

greptile-apps Bot commented Apr 29, 2026 •

edited

Loading

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Flowchart

Uh oh!

Copilot AI left a comment

Uh oh!

bglusman commented Apr 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		bot will route to the default agent. On an unknown user ID, you'll see
		`no identity for telegram/<id>` — use that output to find the ID if needed.

Conversation

bglusman commented Apr 29, 2026

Summary

The two mechanisms

What's defined

What this doesn't do

Merge order

Uh oh!

qodo-code-review Bot commented Apr 29, 2026

Uh oh!

greptile-apps Bot commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Flowchart

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

bglusman commented Apr 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

greptile-apps Bot commented Apr 29, 2026 •

edited

Loading